### Stack:

1. #923 

1. #920 (base) <- This PR

---

## Summary

Adds `run_in_background=true` option to the bash tool, enabling agents
to spawn long-running processes (dev servers, builds, file watchers)
that persist independently.

## Why This Approach

We needed background process support that works identically for both
local and SSH runtimes. A few considerations drove the design:

1. **PTY-based output doesn't fit remote use cases.** For SSH,
maintaining a persistent PTY connection just to let agents read stdout
would be fragile and complex. Agents need to search, filter, and tail
output—not consume a live stream.

2. **File-based output lets agents use standard tools.** By writing
stdout/stderr to files on the target machine, agents can use `tail -f`,
`grep`, `head`, etc. to inspect output. We don't need to reimplement
these filtering capabilities in our own tooling.

3. **A proper long-lived remote daemon is future work.** Ideally, SSH
remotes would have a persistent mux process (or agent binary) that
manages background jobs directly. The user's frontend would just connect
to it. That's a significant architectural change. This PR provides
background shell support without requiring that investment—the
file-based approach works today with no remote-side dependencies.

## Architecture

```
AI Tools (bash, bash_background_list, bash_background_terminate)
    ↓
BackgroundProcessManager (lifecycle, in-memory tracking)
    ↓
Runtime.spawnBackground() (LocalBaseRuntime / SSHRuntime)
    ↓
BackgroundHandle (file-based output & status)
    ↓
backgroundCommands.ts (shared shell builders for Local/SSH parity)
```

## Key Design Decisions

| Decision | Rationale |
|----------|-----------|
| **File-based output** | Works identically for local and SSH, agents
read via `tail`/`cat`/`grep`. |
| **set -m + nohup** | Robust process isolation, PID === PGID for clean
group termination |
| **Workspace-scoped** | Processes tied to workspace, cleaned up on
workspace removal |
| **Lazy status refresh** | No polling overhead, reads `exit_code` file
on list() |
| **Cleanup on compaction** | Background processes terminated before
compaction, as they're not guaranteed to be included (Claude Code does
this too) |

## Tools

- `bash(run_in_background=true)` — spawns process, returns
`stdout_path`/`stderr_path`
- `bash_background_list` — lists processes with status and file paths
- `bash_background_terminate` — kills process group (SIGTERM → wait →
SIGKILL)

## Output Structure

```
/tmp/mux-bashes/{workspaceId}/{bg-xxx}/
├── stdout.log    # Process stdout
├── stderr.log    # Process stderr  
├── exit_code     # Written by trap on exit
└── meta.json     # Process metadata
```

## Technical Details

### Process Spawning

The spawn command uses a subshell with job control enabled:

```bash
(set -m; nohup bash -c 'WRAPPER_SCRIPT' > stdout.log 2> stderr.log < /dev/null & echo $!)
```

**Key elements:**
- `set -m` — Enables bash job control, which makes backgrounded
processes become their own process group leader (PID === PGID). This is
a bash builtin available on all platforms.
- `nohup` — Prevents SIGHUP from killing the process when the terminal
closes.
- Subshell `(...)` — Isolates the process group so the outer shell exits
immediately after echoing the PID.
- `< /dev/null` — Detaches stdin so the process doesn't block waiting
for input.

### Exit Code Detection

The wrapper script sets up a trap to capture the exit code:

```bash
trap 'echo $? > exit_code' EXIT && cd /path && export ENV=val && USER_SCRIPT
```

When the process exits (normally or via signal), the trap writes `$?` to
the `exit_code` file. Mux reads this file to determine if the process is
still running (`exit_code` doesn't exist) or has exited (file contains
the code).

### Process Group Termination

Because `set -m` ensures PID === PGID, we can kill the entire process
tree using a negative PID:

```bash
kill -15 -PID; sleep 2; if kill -0 -PID; then kill -9 -PID; echo 137 > exit_code; else echo 143 > exit_code; fi
```

**Sequence:**
1. Send SIGTERM (`-15`) to the process group (`-PID` targets the group)
2. Wait 2 seconds for graceful shutdown
3. Check if any process in the group survives (`kill -0 -PID`)
4. If still alive, send SIGKILL (`-9`) and record exit code 137
5. Otherwise, record exit code 143 (SIGTERM)

This ensures child processes spawned by the background job are also
terminated, preventing orphaned processes.

### Cross-Platform Compatibility

| Feature | Linux | macOS | Windows (MSYS2) |
|---------|-------|-------|-----------------|
| `set -m` | ✓ bash builtin | ✓ bash builtin | ✓ bash builtin |
| `kill -15/-9 -PID` | ✓ | ✓ | ✓ |
| `nohup` | ✓ | ✓ | ✓ |
| Path format | POSIX | POSIX | Converted via `cygpath` |

Using `set -m` instead of platform-specific tools like `setsid`
(Linux-only) ensures the same code works everywhere.

## Platform Support

- **Linux/macOS/Windows MSYS2**: set -m + nohup pattern (universal)
- **SSH**: Same pattern executed remotely

## Testing

- 20 unit tests in `backgroundProcessManager.test.ts` (including process
group termination)
- 7 unit tests for background execution in `bash.test.ts`
- 6 unit tests in `bash_background_list.test.ts` (including
display_name)
- 5 unit tests in `bash_background_terminate.test.ts`
- 19 unit tests in `backgroundCommands.test.ts`
- 7 runtime tests in `tests/runtime/runtime.test.ts` (Local & SSH)
- 3 end-to-end integration tests in `tests/ipc/backgroundBash.test.ts`
(real AI calls)

_Generated with mux_